Developer CD Series 1998 August: Tool Chest/Dev.CD Aug 98 TC.toast/Tool Chest/Testing & Debugging/Mac OS Development Toolkit/Automation Essentials 2.3.0/Host Automation Folder/VU External Tool libs/FileTool.vuLib

Text File | 1998-03-19 | 17.2 KB | 535 lines | [TEXT/MPS ]

#
#    File:        FileTool.vulib
#
#    Contains:    The tool definition along with the high level tasks to access
#                the tool's services
#
#    Written by:    P. Nagarajan
#
#    Copyright:    © 1993-1997 by Apple Computer, Inc., all rights reserved.
#
#    Change History (most recent first):
#
#        2.2.2    02/04/97    JAS        Added 'vers' resources to library.
#                                    These should always match tool version when tool is revved.
#                02/04/97    JAS        Added task InitFindFolderGlobals()
#         <5>    10/23/96    JAS        Updated Service descriptions to match FileTool docs
#         <4>    07/23/96    SBR        removed StandardServices
#         <3>    07/06/96    SBR        added StandardServices from ThreadedVUTool template
#         <2>    2/1/95        RV        change FileExists return value from integer to boolean symbol
#                3/26/93        NAGA    xxx put comment here xxx
#
#    To Do:
#

tool FileTool s:'FILE'
begin
    # Services specific to FileTool:

    # To create a file
    Service    "Create"( 'string', 'string', 'string' ) return 'integer';
    # First parameter is the full pathname for the file
    # Second parameter is the 4 character creator type ( eg., 'MPS ')
    # Third parameter is the 4 character file type (eg., 'TEXT')
    # Return value is the file reference number for future calls

    # To create a folder
    Service    "CreateFolder"( 'string' ) return 'integer';
    # First parameter is the full pathname for the file
    # Return value is the file reference number for future calls

    # To delete a file/folder
    Service    "Delete"( 'string', 'integer' );
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Once a file/folder is deleted its reference number is no longer valid

    # To erase the contents of the data fork of a file
    Service    "Erase"( 'string', 'integer' ) return 'integer';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool

    # To check if a file exists
    Service    "FileExists"( 'string' ) return 'symbol';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Return value is 1 if file exists else 0

    # To copy a file
    Service    "CopyFile"( 'string', 'integer', 'string' ) return 'integer';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool. This can be zero if the first parameter
    # is fully specified.
    # Third parameter is the full pathname for the new file
    # Return value is 1 if file copied else 0

    # To get back memory in the FileTool heap
    Service    "ForgetFile"( 'string', 'integer' ) return 'integer';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Return value is insignificant

    # To move a file/folder
    Service    "Move"( 'string', 'integer', 'string' ) return 'integer';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Third parameter is the new file path name
    # Return value is the file reference number for future calls

    # To read from a file a specified number of characters
    Service    "Read"( 'string', 'integer', 'integer', 'integer' ) return 'string';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Third parameter is the number of characters to be read
    # Fourth parameter is the number of characters from start of file after
    # which to start reading
    # Return value is the string read from the file

    # To read from a file until a specified character is seen
    Service    "ReadUntil"( 'string', 'integer', 'string', 'integer' ) return 'string';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Third parameter is the single character string that indicates the
    # character until which the contents of a file has to be read
    # Fourth parameter is the number of characters from start of file after
    # which to start reading
    # Return value is the string read from the file

    # To read a specific line from a file
    Service    "ReadLine"( 'string', 'integer', 'integer', 'string' ) return 'string';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Third parameter is the number of the desired line
    # Fourth parameter is the character that terminates lines, e.g. "\r"
    # Return value is the string read from the file

    # To rename a file/folder
    Service    "Rename"( 'string', 'integer', 'string' ) return 'integer';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Third parameter is the new file name (not a path name)
    # Return value is the file reference number for future calls

    # To get back the list of mounted volume names
    Service    "VolumeList"() return 'list';

    # To write to the data fork of a file
    Service    "Write"( 'string', 'integer', 'string' ) return 'integer';
    # First parameter is the full pathname for the file (can be '', if second
    # parameter is given non zero value)
    # Second parameter if non-zero is the file reference previously
    # returned by the tool
    # Third parameter is the text to be appended to (written at the end
    # of) the file specified by the first two parameters
    # Return value is the file reference number for future calls

    # To append the second file to the first, both must be text files
    Service    "AppendFile"( 'string', 'string' ) return 'symbol';

    # To locate the special folders defined by the system
    Service    "FindFolder"( 'string' ) return 'string';
    # First parameter is the four character code for the folder, the FolderType
    # The full path name to the folder is returned

    # Read the short & long version string from the specified file
    Service    "ReadVersion"( 'string', 'integer' ) return 'list';

    # Test if a resource exists within a specified file
    Service    "ResourceExists"( 'string', 'string', 'integer' ) return 'symbol';
    # Return value is true if the resource exists.

    # Read the 'SIZE' resource from an application file
    Service    "ReadSizeResource"( 'string', 'integer' ) return 'list';
    # First parameter is the full pathname of the application
    # Second parameter is the ID of the 'SIZE' resource to be read
    # Returns the preferred and minimum memory partitions (in bytes)

    # Services common to all Virtual User external tools:
    Service "Initialize"( 'undefined' ); # pass TRUE for target, FALSE for host
    Service "Cancel"( 'string' );
    Service "GetToolServices"() return 'list';
    Service "GetToolVersion"() return 'list';
    Service "ServiceSupported"( 'string' ) return 'undefined';
    Service "Quit"();

end;

task CreateFile( pFilePathName, pSignature := 'MPS ', pType := 'TEXT' )
begin
    return FileTool( "Create", pFilePathName, pSignature, pType );
end;

task CreateFolder( pFolderPathName )
begin
    return FileTool( "CreateFolder", pFolderPathName );
end;

task DeleteFile( pFileReference )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber as parameters
    return FileTool( "Delete", tFilePathStr, tFileReferenceNumber );

end;

# This task will empty the contents of the specified file (dataFork only)
# the file will not be deleted
task EraseFile( pFileReference )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber as parameters
    return FileTool( "Erase", tFilePathStr, tFileReferenceNumber );

end;

task FileExists( pFilePathName )
begin
    if( typeOf( pFilePathName ) <> 'string' )
    begin
        return -50;#gParamError = -50, same as what the tool returns
    end;

    # Now call the tool with pFilePathName as parameter
    return FileTool( "FileExists", pFilePathName );

end;

task CopyFile( pFileReference, pDestPathName )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pDestPathName as parameters
    return FileTool( "CopyFile", tFilePathStr, tFileReferenceNumber, pDestPathName );

end;

# This task will free up memory in the FileTool
# the file will not be touched or affected in any way
task ForgetFile( pFileReference )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber as parameters
    return FileTool( "ForgetFile", tFilePathStr, tFileReferenceNumber );

end;

task MoveFile( pFileReference, pNewPathName )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pNewPathName as parameters
    return FileTool( "Move", tFilePathStr, tFileReferenceNumber, pNewPathName );

end;

task RenameFile( pFileReference, pNewName )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pNewName as parameters
    return FileTool( "Rename", tFilePathStr, tFileReferenceNumber, pNewName );

end;

task VolumeList()
begin

    # Now call the tool
    return FileTool( "VolumeList" );

end;

# a utility task used by WriteToFile
task ToText( pData )
begin
    if( typeOf( pData ) = 'string' ) return pData;
    if( typeOf( pData ) = 'integer' ) return NumToStr( pData );
    return undefined; # else
end;

# This task will append pData to end of the specified file
# pData can a string or a list of strings and numbers
task WriteToFile( pFileReference, pData )
begin
    tText := '';
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    if( typeOf( pData ) = 'list' )
    begin
        for i := 1 to card pData
        begin
            tNext := ToText( pData[i] );
            if( tNext )
                tText := tText + tNext;
            else
                return -50;
        end;
    end;
    else if( typeOf( pData ) = 'string' )
    begin
        tText := pData;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and tText as parameters
    return FileTool( "Write", tFilePathStr, tFileReferenceNumber, tText );

end;


task Read( pFileReference, pNumOfCharacters, pFromPosition := 0 )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pNumOfCharacters as parameters
    return FileTool( "Read", tFilePathStr, tFileReferenceNumber, pNumOfCharacters, pFromPosition );

end;

task ReadUntil( pFileReference, pUntilCharacter, pFromPosition := 0 )
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;#gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pUntilCharacter as parameters
    return FileTool( "ReadUntil", tFilePathStr, tFileReferenceNumber, pUntilCharacter, pFromPosition );

end;

task ReadLine( pFileReference, pLineNumber := 0, pLineTermChar := "∂n")
begin
    if( typeOf( pFileReference ) = 'integer' )
    begin
        tFilePathStr := '';
        tFileReferenceNumber := pFileReference;
    end;
    else if( typeOf( pFileReference ) = 'string' )
    begin
        tFilePathStr := pFileReference;
        tFileReferenceNumber := 0;
    end;
    else
        return -50;    #gParamError = -50, same as what the tool returns

    # Now call the tool with tFilePathStr, tFileReferenceNumber and pUntilCharacter as parameters
    return FileTool( "ReadLine", tFilePathStr, tFileReferenceNumber,
                            pLineNumber, pLineTermChar );

end;




task AppendFile( pTargetFile, pSourceFile )
begin
    if not ( typeOf( pTargetFile ) = 'string' )
    begin
        return { -50 };#gParamError = -50, same as what the tool returns
    end;

    if not ( typeOf( pSourceFile ) = 'string' )
    begin
        return { -50 };#gParamError = -50, same as what the tool returns
    end;

    # Now call the tool with tTargetFile, tSourceFile
    x := FileTool( "AppendFile", pTargetFile, pSourceFile );
    return x;
end;


#########################################################################
#    task        InitFindFolderGlobals()
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    Description:    Initializes global constants for use with FindFolder
#
#    Parameters:        None
#
#    Returns:        Nothing
#
#    Example:        InitFindFolderGlobals()
#
#    Assumptions:    VU 2.1
#∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞
#    History:
#        02/04/97    JAS            created
#########################################################################
task InitFindFolderGlobals()
begin
    # global constants used by FindFolder:

    global kSystemFolderType            := "macs";    # the system folder
    global kDesktopFolderType            := 'desk';    # the desktop folder; objects in this folder show on the desk top.
    global kTrashFolderType                := 'trsh';    # the trash folder; objects in this folder show up in the trash
    global kWhereToEmptyTrashFolderType := 'empt';    # the "empty trash" folder; Finder starts empty from here down
    global kPrintMonitorDocsFolderType    := 'prnt';    # Print Monitor documents
    global kStartupFolderType            := 'strt';    # Finder objects (applications, documents, DAs, aliases, to...) to open at startup go here
    global kShutdownFolderType            := 'shdf';    # Finder objects (applications, documents, DAs, aliases, to...) to open at shutdown go here
    global kAppleMenuFolderType            := 'amnu';    # Finder objects to put into the Apple menu go here
    global kControlPanelFolderType        := 'ctrl';    # Control Panels go here (may contain INITs)
    global kExtensionFolderType            := 'extn';    # Finder extensions go here
    global kFontsFolderType                := 'font';    # Fonts go here
    global kPreferencesFolderType        := 'pref';    # preferences for applications go here
    global kTemporaryFolderType            := 'temp';    # the Temporary Folder inside the System folder
end;



task FindFolder( FolderType )
begin
    if not ( typeOf( FolderType ) = 'string' )
    begin
        return { errAEWrongParameters, undef, "Bad FolderType parameter" };
    end;

    if ( card( FolderType ) > 4 ) or ( card( FolderType ) <= 0 )
    begin
        return { errAEWrongParameters, undef, "Bad FolderType parameter" };
    end;

    x := FileTool( "FindFolder", FolderType );
    return x;
end;

task ReadVersion( FilePathName, pVersID := 1 )
begin
    x := FileTool( "ReadVersion", FilePathName, pVersID );
    SErr := ScriptError();
    return { x[1], x[2], x[3], SErr };
end;

task ResourceExists( FilePathName, pResType, pResID )
begin
    x := FileTool( "ResourceExists", FilePathName, pResType, pResID );
    SErr := ScriptError();
    return { x[1], x[2], x[3], SErr };
end;

task ReadSizeResource( FilePathName, pResID )
begin
    x := FileTool( "ReadSizeResource", FilePathName, pResID );
    SErr := ScriptError();
    return { x[1], x[2], x[3], SErr };
end;